Inside Macintosh: QuickDraw GX Graphics /

Chapter 4 - Geometric Operations / Geometric Operations Reference

Functions / Getting and Setting Shape Bounds

GXSetShapeBounds

You can use the GXSetShapeBounds function to change a shape's bounding rectangle, thereby moving and resizing the shape.

void GXSetShapeBounds(gxShape target, 
                      const gxRectangle *newBounds);

source

A reference to the shape whose bounding rectangle you want to change.

newBounds

The new bounding rectangle.

DESCRIPTION

The GXSetShapeBounds function changes the bounding rectangle of the shape specified by the source parameter to be the rectangle specified by the newBounds parameter.

How this function changes the bounding rectangle is determined by the source shape's gxMapTransformShape shape attribute:

• If the gxMapTransformShape shape attribute is not set, the function changes the geometry of the source shape to fit the new bounding rectangle.
• If the gxMapTransformShape shape attribute is set, the function does not alter the shape's geometry directly; instead, it changes the mapping of the shape's transform object to scale the shape to fit in the new bounding rectangle.

By changing a shape's bounding rectangle, you can move the shape as well as scale it in the horizontal and vertical dimensions.

For empty and full shapes, this function does nothing.

If you provide a point shape as the target shape and a new bounding rectangle that has height or width, this function posts the warning scale_shape_out_of_range.

If you provide a target shape that is not one of the geometric shape types, this function performs the actions described in the following table:

Shape type	Action taken
bitmap	Calls the GXMapShape function
picture	Calls the GXMapShape function
text	Converts to a path shape if necessary (when the ratio between the height of the new bounding rectangle and the height of the original bounding rectangle is not the same as the ratio between the width of the new bounding rectangle and the width of the original bounding rectangle)
glyph	Converts to a path shape if necessary
layout	Converts to a path shape if necessary

ERRORS, WARNINGS, AND NOTICES

Errors
out_of_memory
shape_is_nil
shape_access_not_allowed	(debugging version)
functionality_unimplemented	(debugging version)
Warnings
scale_shape_out_of_range
character_substitution_took_place
font_substitution_took_place
unable_to_traverse_open_contour_that_starts_or_ends_off_the_curve
	(debugging version)
shape_passed_has_no_bounds	(debugging version)

SEE ALSO

For examples of this function, see "Setting a Shape's Bounding Rectangle" beginning on page 4-47.

For a discussion of rectangles and bounding rectangles, see Chapter 2, "Geometric Shapes," in this book.

For a discussion of the gxMapTransformShape shape attribute, see the chapters "Shape Objects" and "Transform Objects" in Inside Macintosh: QuickDraw GX Objects.

To determine the bounding rectangle of a shape, use the GXGetShapeBounds function, described on page 4-90.

Main | Page One | What's New | Apple Computer, Inc. | Find It | Contact Us | Help